Crate bee_ternary[][src]

Expand description

A general-purpose ternary manipulation, translation and encoding crate.

Features

  • Creation of trit and tryte buffers with multiple encodings
  • Safe encoding API that allows the efficient manipulation and sharing of trit and tryte buffers and slices
  • Mutation of trit buffers and slices
  • Ternary BigInt implementation
  • Balanced and unbalanced ternary
  • serde support

Encodings

This crate includes support for many different trit encodings. Encodings allow the trading off of different features against each other.

T1B1 is the canonical default encoding and represents every trit with a single byte of memory. It is the fastest encoding to manipulate since no bitwise operations are necessary to pack and unpack it from memory during manipulation. As a result of this, it also permits certain extra features like mutable chunking and accessing its contents through ordinary slices.

T3B1 is also commonly used. It provides good compression and has the advantage that it has an identical bit representation as a Tryte slice. For this reason, it is the only encoding that can be converted to a tryte slice with no overhead.

T5B1 is the most compressed encoding. It provides very high storage densities (almost optimal, in fact) and is the densest encoding supported by this crate.

It is likely that one of the 3 encodings above will suit your requirements. In addition, this crate also supports T2B1 and T4B1 for completeness.

Byte Alignment

This crate supports creating sub-slices of trit slices. To enable this, it stores extra metadata along with a trit slice in order to correct identify the index of a buffer it starts on. With compressed encodings, such as T3B1, that starting index (and, indeed, the end index) may not fall exactly on a byte boundary.

This crate makes a best attempt at avoiding the negative ramifications of this fact, but sadly some still leak through into the API. For example, some methods may panic if a slice does not have a byte-aligned starting index or otherwise does not fulfil certain invariants. However, all panicking behaviours are documented on each method such that you can easily avoid circumstances like this.

When the documentation refers to ‘byte alignment’, it is referring specifically to whether the starting index is a multiple of the compression factor. For example a byte-aligned T3B1 buffer will always start on an index of the original buffer that is a multiple of 3.

Re-exports

pub use crate::t1b1::T1B1Buf;
pub use crate::t1b1::T1B1;
pub use crate::t2b1::T2B1Buf;
pub use crate::t2b1::T2B1;
pub use crate::t3b1::T3B1Buf;
pub use crate::t3b1::T3B1;
pub use crate::t4b1::T4B1Buf;
pub use crate::t4b1::T4B1;
pub use crate::t5b1::T5B1Buf;
pub use crate::t5b1::T5B1;
pub use crate::trit::Btrit;
pub use crate::trit::ShiftTernary;
pub use crate::trit::Trit;
pub use crate::trit::Utrit;
pub use crate::tryte::Tryte;
pub use crate::tryte::TryteBuf;

Modules

Utility functions for encoding and decoding B1T6 encoding.

Conversions between to and from standard types.

Types and traits that allow the implementation of new encoding formats.

The T1B1 and T1B1Buf encodings.

The T2B1 and T2B1Buf encodings.

The T3B1 and T3B1Buf encodings.

The T4B1 and T4B1Buf encodings.

The T5B1 and T5B1Buf encodings.

Types and traits used to represent trits, both balanced and unbalanced.

Types and traits used to represent trytes and buffers of trytes.

Structs

A buffer containing trits.

A type that represents a buffer of trits of unknown length.

Enums

An error that may be produced as a result of fallible conversions.